Inside Macintosh: QuickDraw GX Graphics /

Chapter 2 - Geometric Shapes / Geometric Shapes Reference

Functions / Editing Shape Geometries

GXSetShapeParts

You can use the GXSetShapeParts function to replace a range of geometric points in a shape's geometry with the information in another shape's geometry.

void GXSetShapeParts(gxShape target, long index, long count, 
                     gxShape insert, gxEditShapeFlag flags);

target

A reference to the shape whose geometry you want to edit.

index

The geometry index of the first geometric point to replace. A value of 0 indicates that the new information should be inserted after the final geometric point in the target shape's geometry.

count

How many geometric points to replace. A value of 0 indicates that no geometric points should be replaced; instead, the new information is inserted before the geometric point specified by the index parameter. If you pass the gxSelectToEnd constant for this parameter, all geometric points from the one specified by the index parameter to the final one are replaced.

insert

A reference to the shape whose geometry you want to insert. You may specify the gxSetToNil constant for this parameter to indicate that you want to delete points from the target shape's geometry.

flags

A set of flags that determine how the new geometry information is inserted in the target shape's geometry.

DESCRIPTION

The GXSetShapeParts function replaces geometry information in the target shape's geometry with the geometry information in the shape specified by the insert parameter. The index and count parameters determine what part of the original geometry is replaced. The flags parameter determines how the new information is inserted in the geometry.

This function converts the shape type of the target shape to be suitable to hold the information from the inserted shape. For example, if the target shape is a line and the inserted shape is a rectangle, this function converts the target shape to a polygon shape before inserting the rectangle.

If the target shape is a rectangle, you may only insert information before both geometric points, after both geometric points, or in place of both geometric points.

You may add any shape to an empty target shape--the result will be identical to the inserted shape. You may also add any shape to a full target shape, but the result will also be a full shape.

The index parameter indicates the first geometric point to be replaced. If you pass a value of 0 for this parameter, no geometric points are replaced. Instead, this function inserts the new geometry information after the last geometric point of the target shape's original geometry. If you pass a 0 for this parameter, you must pass a 0 or the gxSelectToEnd constant for the count parameter.

The count parameter indicates how many geometric points in the original geometry should be replaced. If you pass a value of 0 for this parameter, no geometric points are replaced; instead, this function inserts the new geometry information before the geometric point indicated by the index parameter. If you pass the gxSelectToEnd constant for this parameter, the function replaces all geometric points in the original geometry starting with the geometric point indicated by the index parameter.

When this function inserts the new geometry information, it retains the contour breaks contained in the inserted shape's geometry. For example, if you provide a path shape for the inserted shape that contains two contours, the break between those contours remains when the geometric points are inserted into the target shape's geometry.

The flags parameter indicates how you want the function to merge the first geometric point and the last geometric point of the inserted shape's geometry into the target shape's geometry. The possible flags are:

gxBreakNeitherEdit         = 0
gxBreakLeftEdit            = 0x01
gxBreakRightEdit           = 0x02
gxRemoveDuplicatePoints    = 0x04

The gxBreakNeitherEdit value indicates that the first geometric point of the inserted shape's geometry should be merged into the preceding contour of the target shape's geometry and the final geometric point of the inserted shape's geometry should be merged into the subsequent contour.

The gxBreakLeftEdit flag indicates that the first geometric point of the inserted shape's geometry should begin a new contour once inserted in the target shape's geometry. The gxBreakRightEdit flag indicates that the geometric point in the target shape that follows the final geometric point of the inserted shape's geometry (after the new information is inserted) should begin a new contour.

The gxRemoveDuplicatePoints flag indicates that this function should, when inserting the information from the inserted shape's geometry, remove the first geometric point of this inserted geometry if it exactly matches the preceding point in the existing geometry. Similarly, this flag indicates that the final geometric point of the inserted shape's geometry should be removed if it exactly matches the subsequent geometric point in the target shape's geometry.

If you provide a source shape that is a full shape, this function returns a full shape in the destination parameter.

If you provide a source shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Posts the error shape_operator_may_not_be_a_bitmap
picture	Calls the GXSetPictureParts function
text	Calls the GXSetTextParts function
glyph	Calls the GXSetGlyphParts function
layout	Calls the GXSetLayoutParts function

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
index_is_less_than_one	(debugging version)
count_is_less_than_one	(debugging version)
functionality_unimplemented	(debugging version)
rectangles_cannot_be_inserted_into	(debugging version)
shape_operator_may_not_be_a_bitmap	(debugging version)
shape_access_not_allowed	(debugging version)
Warnings
index_out_of_range
count_out_of_range
picture_cannot_contain_itself
Notices
parameters_have_no_effect	(debugging version)

SEE ALSO

For an example of this function, see "Editing Shape Parts" beginning on page 2-93.

To learn how this function works for typographic shape types, see Inside Macintosh: QuickDraw GX Typography.

For information about other functions that allow you to edit information in shape geometries, see the description of the GXSetShapePoints function on page 2-142, the description of the GXSetPolygonParts function on page 2-145, and the description of the GXSetPathParts function on page 2-149.

To copy parts of a shape's geometry, use the GXGetShapeParts function, which is described on page 2-152.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help